API klaidų tvarkymas: išsamus HTTP būsenos kodų vadovas

Programinės įrangos kūrimo pasaulyje API (aplikacijų programavimo sąsajos) tapo modernių programų pagrindu, leidžiančiu sklandžiai bendrauti ir keistis duomenimis tarp skirtingų sistemų. Kadangi API tampa vis sudėtingesnės ir svarbesnės verslo operacijoms visame pasaulyje, tinkamas klaidų tvarkymas tampa itin svarbus. Vienas iš esminių API klaidų tvarkymo aspektų yra HTTP būsenos kodų naudojimas. Šiame vadove pateikiama išsami HTTP būsenos kodų apžvalga ir kaip juos galima efektyviai naudoti kuriant patikimas API, kurios teikia aiškius ir informatyvius klaidų pranešimus kūrėjams visame pasaulyje.

Kas yra HTTP būsenos kodai?

HTTP būsenos kodai yra trijų skaitmenų kodai, kuriuos serveris grąžina atsakydamas į kliento užklausą. Jie suteikia informacijos apie užklausos rezultatą, nurodydami, ar ji buvo sėkminga, ar įvyko klaida, ar reikia imtis tolesnių veiksmų. Šie kodai yra esminė HTTP protokolo dalis ir yra standartizuoti Interneto inžinerijos darbo grupės (IETF) RFC 7231 ir kituose susijusiuose RFC dokumentuose.

HTTP būsenos kodai skirstomi į penkias klases, kurių kiekviena atspindi skirtingą atsakymų kategoriją:

• 1xx (Informaciniai): Užklausa gauta ir yra apdorojama. Šie kodai retai naudojami API klaidų tvarkymui.
• 2xx (Sėkmė): Užklausa buvo sėkmingai gauta, suprasta ir priimta.
• 3xx (Peradresavimas): Klientas turi imtis tolesnių veiksmų, kad užbaigtų užklausą.
• 4xx (Kliento klaida): Užklausoje yra klaidinga sintaksė arba jos negalima įvykdyti. Tai rodo klaidą kliento pusėje.
• 5xx (Serverio klaida): Serveriui nepavyko įvykdyti galiojančios užklausos. Tai rodo klaidą serverio pusėje.

Kodėl HTTP būsenos kodai yra svarbūs API klaidų tvarkymui?

HTTP būsenos kodai yra labai svarbūs efektyviam API klaidų tvarkymui dėl kelių priežasčių:

• Standartizuotas bendravimas: Jie suteikia standartizuotą būdą serveriui pranešti klientui apie užklausos rezultatą. Tai leidžia kūrėjams lengvai suprasti ir tvarkyti klaidas, nereikalaujant interpretuoti individualių klaidų pranešimų.
• Geresnė kūrėjo patirtis: Aiškūs ir informatyvūs klaidų pranešimai, kartu su atitinkamais HTTP būsenos kodais, žymiai pagerina kūrėjo patirtį. Tai leidžia kūrėjams greitai nustatyti ir išspręsti problemas, sutrumpinant kūrimo laiką ir mažinant nusivylimą.
• Padidintas API patikimumas: Teikdami išsamią informaciją apie klaidas, HTTP būsenos kodai leidžia kūrėjams kurti tvirtesnes ir patikimesnes programas, kurios gali sklandžiai tvarkyti netikėtas situacijas.
• Supaprastintas derinimas: HTTP būsenos kodai supaprastina derinimą, aiškiai nurodydami klaidos šaltinį (kliento ar serverio pusėje).
• Globalus nuoseklumas: Kuriant API globaliai auditorijai, standartizuoti klaidų kodai yra būtini norint užtikrinti nuoseklų elgesį skirtinguose regionuose ir kalbose. Tai padeda išvengti dviprasmybių ir leidžia kūrėjams iš viso pasaulio lengvai suprasti ir spręsti problemas.

Dažniausiai naudojami HTTP būsenos kodai ir jų reikšmės

Štai keletas dažniausiai naudojamų HTTP būsenos kodų, taikomų API klaidų tvarkymui:

2xx sėkmės kodai

• 200 OK: Užklausa buvo sėkminga. Tai standartinis atsakymas sėkmingoms GET, PUT, PATCH ir DELETE užklausoms.
• 201 Created: Užklausa buvo sėkminga ir buvo sukurtas naujas išteklius. Paprastai naudojamas po sėkmingos POST užklausos. Pavyzdžiui, kuriant naują vartotojo paskyrą.
• 204 No Content: Užklausa buvo sėkminga, bet nėra turinio, kurį būtų galima grąžinti. Dažnai naudojamas DELETE užklausoms, kai atsakymo turinys nereikalingas.

3xx peradresavimo kodai

• 301 Moved Permanently: Užklaustas išteklius buvo visam laikui perkeltas į naują URL. Klientas turėtų atnaujinti savo nuorodas, kad jos vestų į naują URL.
• 302 Found: Užklaustas išteklius laikinai yra kitame URL. Klientas turėtų toliau naudoti originalų URL būsimoms užklausoms. Dažnai naudojamas laikiniems peradresavimams.
• 304 Not Modified: Kliento talpykloje esanti ištekliaus versija vis dar galioja. Serveris nurodo klientui naudoti talpykloje esančią versiją. Tai taupo pralaidumą ir gerina našumą.

4xx kliento klaidų kodai

Šie kodai rodo, kad klientas padarė klaidą užklausoje. Jie yra labai svarbūs informuojant klientą, kas nutiko negerai, kad jis galėtų ištaisyti užklausą.

• 400 Bad Request: Užklausos serveris negalėjo suprasti dėl neteisingos sintaksės ar negaliojančių parametrų. Pavyzdžiui, jei trūksta privalomo lauko arba jo duomenų tipas yra neteisingas.
• 401 Unauthorized: Užklausai reikalinga autentifikacija. Klientas turi pateikti galiojančius prisijungimo duomenis (pvz., API raktą ar JWT prieigos raktą). Pavyzdžiui, bandant pasiekti apsaugotą išteklių neprisijungus.
• 403 Forbidden: Klientas yra autentifikuotas, bet neturi leidimo pasiekti užklaustą išteklių. Pavyzdžiui, vartotojui bandant pasiekti tik administratoriui skirtą išteklių.
• 404 Not Found: Užklaustas išteklius serveryje nerastas. Tai dažna klaida, kai klientas bando pasiekti neegzistuojantį URL. Pavyzdžiui, bandant pasiekti vartotojo profilį su neteisingu ID.
• 405 Method Not Allowed: Užklausoje použitý HTTP metodas nepalaikomas užklaustam ištekliui. Pavyzdžiui, bandant naudoti POST užklausą tik skaitymui skirtame galutiniame taške.
• 409 Conflict: Užklausos negalima įvykdyti dėl konflikto su dabartine ištekliaus būsena. Pavyzdžiui, bandant sukurti išteklių su unikaliu identifikatoriumi, kuris jau egzistuoja.
• 415 Unsupported Media Type: Serveris nepalaiko užklausos turinio medijos tipo. Pavyzdžiui, siunčiant JSON duomenis į galutinį tašką, kuris priima tik XML.
• 422 Unprocessable Entity: Užklausa buvo gerai suformuota, bet negalėjo būti apdorota dėl semantinių klaidų. Dažnai naudojama patvirtinimo klaidoms. Pavyzdžiui, pateikiant formą su neteisingu el. pašto formatu arba slaptažodžiu, kuris neatitinka sudėtingumo reikalavimų.
• 429 Too Many Requests: Klientas per tam tikrą laiką išsiuntė per daug užklausų. Tai naudojama užklausų skaičiaus ribojimui. Pavyzdžiui, ribojant API iškvietimų skaičių, kurį vartotojas gali atlikti per valandą.

5xx serverio klaidų kodai

Šie kodai rodo, kad serveris susidūrė su klaida apdorodamas užklausą. Paprastai jie rodo problemą serverio pusėje ir reikalauja tyrimo.

• 500 Internal Server Error: Bendrinis klaidos pranešimas, nurodantis, kad serveris susidūrė su netikėta sąlyga. To reikėtų vengti, kai įmanoma, pateikiant konkretesnius klaidų pranešimus.
• 502 Bad Gateway: Serveris, veikdamas kaip šliuzas ar tarpinis serveris, gavo neteisingą atsakymą iš kito serverio. Tai dažnai rodo problemą su aukštesnio lygio serveriu.
• 503 Service Unavailable: Serveris šiuo metu negali apdoroti užklausos dėl laikinos perkrovos ar techninės priežiūros. Pavyzdžiui, per planinę techninę priežiūrą ar staigų srauto padidėjimą.
• 504 Gateway Timeout: Serveris, veikdamas kaip šliuzas ar tarpinis serveris, laiku negavo atsakymo iš kito serverio. Tai rodo delsos problemą su aukštesnio lygio serveriu.

Geriausios praktikos diegiant HTTP būsenos kodus API

Norėdami efektyviai naudoti HTTP būsenos kodus savo API, apsvarstykite šias geriausias praktikas:

• Pasirinkite tinkamą kodą: Atidžiai pasirinkite tinkamiausią HTTP būsenos kodą, kuris tiksliai atspindi klaidos pobūdį. Venkite naudoti bendrinius kodus, tokius kaip 500 Internal Server Error, kai yra prieinamas konkretesnis kodas.
• Pateikite informatyvius klaidų pranešimus: Kiekvieną HTTP būsenos kodą papildykite aiškiu ir glaustu klaidų pranešimu, kuris paaiškina klaidos priežastį ir siūlo, kaip ją išspręsti. Klaidos pranešimas turėtų būti skaitomas žmogui ir lengvai suprantamas įvairių sričių kūrėjams.
• Naudokite nuoseklius klaidų formatus: Nustatykite nuoseklų klaidų atsakymų formatą, įskaitant HTTP būsenos kodą, klaidos pranešimą ir bet kokią susijusią klaidų informaciją. JSON yra dažniausiai naudojamas API atsakymų formatas.
• Registruokite klaidas: Registruokite visas API klaidas serverio pusėje, įskaitant HTTP būsenos kodą, klaidos pranešimą, užklausos duomenis ir bet kokią susijusią konteksto informaciją. Tai padės greičiau nustatyti ir išspręsti problemas.
• Sklandžiai tvarkykite išimtis: Įdiekite tinkamą išimčių tvarkymą savo kode, kad išvengtumėte netikėtų klaidų, kurios gali sugadinti jūsų programą. Sugaukite išimtis ir grąžinkite klientui atitinkamus HTTP būsenos kodus bei klaidų pranešimus.
• Dokumentuokite savo API: Aiškiai dokumentuokite visus galimus HTTP būsenos kodus ir klaidų pranešimus, kuriuos gali grąžinti jūsų API. Tai padės kūrėjams suprasti, kaip tvarkyti klaidas ir kurti tvirtesnes integracijas. Įrankiai, tokie kaip Swagger/OpenAPI, gali automatiškai generuoti API dokumentaciją.
• Įdiekite užklausų skaičiaus ribojimą: Apsaugokite savo API nuo piktnaudžiavimo įdiegdami užklausų skaičiaus ribojimą. Grąžinkite 429 Too Many Requests klaidą, kai klientas viršija užklausų limitą. Tai padeda užtikrinti, kad jūsų API liks prieinama visiems vartotojams.
• Stebėkite savo API: Stebėkite savo API dėl klaidų ir našumo problemų. Nustatykite perspėjimus, kad būtumėte informuoti, kai įvyksta klaidos, kad galėtumėte greitai jas ištirti ir išspręsti. Įrankiai, tokie kaip Datadog, New Relic ir Prometheus, gali būti naudojami API stebėsenai.
• Apsvarstykite lokalizavimą (internacionalizaciją): Kuriant API globaliai auditorijai, apsvarstykite klaidų pranešimų lokalizavimą į skirtingas kalbas. Tai žymiai pagerina kūrėjų, nekalbančių angliškai, patirtį. Galite naudoti vertimo paslaugą arba išteklių rinkinius vertimams tvarkyti.

HTTP būsenos kodų naudojimo pavyzdžiai

Štai keletas praktinių pavyzdžių, kaip HTTP būsenos kodai gali būti naudojami skirtinguose API scenarijuose:

1 pavyzdys: Vartotojo autentifikavimas

Klientas bando autentifikuotis API naudodamas neteisingus prisijungimo duomenis.

Užklausa:

POST /auth/login
Content-Type: application/json

{
  "username": "invalid_user",
  "password": "wrong_password"
}

Atsakymas:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "code": "invalid_credentials",
    "message": "Neteisingas vartotojo vardas arba slaptažodis"
  }
}

Šiame pavyzdyje serveris grąžina 401 Unauthorized būsenos kodą, nurodydamas, kad klientui nepavyko autentifikuotis. Atsakymo turinyje yra JSON objektas su klaidos kodu ir pranešimu, paaiškinančiu klaidos priežastį.

2 pavyzdys: Išteklius nerastas

Klientas bando gauti išteklių, kuris neegzistuoja.

Užklausa:

GET /users/12345

Atsakymas:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "code": "resource_not_found",
    "message": "Vartotojas su ID 12345 nerastas"
  }
}

Šiame pavyzdyje serveris grąžina 404 Not Found būsenos kodą, nurodydamas, kad užklaustas išteklius neegzistuoja. Atsakymo turinyje yra JSON objektas su klaidos kodu ir pranešimu, paaiškinančiu, kad vartotojas su nurodytu ID nebuvo rastas.

3 pavyzdys: Patvirtinimo klaida

Klientas bando sukurti naują išteklių su neteisingais duomenimis.

Užklausa:

POST /users
Content-Type: application/json

{
  "name": "",
  "email": "invalid_email"
}

Atsakymas:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "errors": [
    {
      "field": "name",
      "code": "required",
      "message": "Vardas yra privalomas"
    },
    {
      "field": "email",
      "code": "invalid_format",
      "message": "El. paštas nėra galiojantis el. pašto adresas"
    }
  ]
}

Šiame pavyzdyje serveris grąžina 422 Unprocessable Entity būsenos kodą, nurodydamas, kad užklausa buvo gerai suformuota, bet negalėjo būti apdorota dėl patvirtinimo klaidų. Atsakymo turinyje yra JSON objektas su klaidų sąrašu, kurių kiekvienoje nurodomas laukas, sukėlęs klaidą, klaidos kodas ir pranešimas, paaiškinantis klaidą.

HTTP būsenos kodai ir API saugumas

Tinkamas HTTP būsenos kodų naudojimas taip pat gali prisidėti prie API saugumo. Pavyzdžiui, vengiant pernelyg išsamių klaidų pranešimų, galima užkirsti kelią puolėjams gauti jautrios informacijos apie jūsų sistemą. Tvarkant autentifikavimo ir autorizacijos klaidas, svarbu grąžinti nuoseklius ir neatskleidžiančius klaidų pranešimus, siekiant išvengti paskyrų išvardijimo ar kitų atakų.

Ne tik standartiniai HTTP būsenos kodai: individualūs klaidų kodai

Nors standartiniai HTTP būsenos kodai apima platų scenarijų spektrą, gali būti atvejų, kai reikia apibrėžti individualius klaidų kodus, kad būtų pateikta konkretesnė informacija apie klaidą. Naudojant individualius klaidų kodus, rekomenduojama juos įtraukti į atsakymo turinį kartu su standartiniu HTTP būsenos kodu. Tai leidžia klientams lengvai nustatyti klaidos tipą ir imtis atitinkamų veiksmų.

Įrankiai API klaidų tvarkymo testavimui

Keli įrankiai gali padėti jums išbandyti ir patvirtinti jūsų API klaidų tvarkymą:

• Postman: Populiarus API klientas, leidžiantis siųsti užklausas į jūsų API ir tikrinti atsakymus, įskaitant HTTP būsenos kodus ir klaidų pranešimus.
• Swagger Inspector: Įrankis, leidžiantis išbandyti jūsų API pagal OpenAPI apibrėžimą ir nustatyti bet kokius neatitikimus klaidų tvarkyme.
• Automatizuoto testavimo karkasai: Naudokite automatizuoto testavimo karkasus, tokius kaip Jest, Mocha ar Pytest, kad rašytumėte testus, kurie patikrintų jūsų API klaidų tvarkymo teisingumą.

Išvada

HTTP būsenos kodai yra pagrindinis API klaidų tvarkymo aspektas ir yra būtini kuriant tvirtas, patikimas ir vartotojui draugiškas API, skirtas globaliai auditorijai. Suprasdami skirtingus HTTP būsenos kodus ir laikydamiesi geriausių jų diegimo praktikų, galite žymiai pagerinti kūrėjo patirtį, supaprastinti derinimą ir pagerinti bendrą savo API kokybę. Nepamirškite pasirinkti tinkamą kodą, pateikti informatyvius klaidų pranešimus, naudoti nuoseklius klaidų formatus ir išsamiai dokumentuoti savo API. Taip sukursite API, kurias lengviau naudoti, kurios yra patikimesnės ir geriau pasirengusios atlaikyti nuolat besikeičiančio skaitmeninio pasaulio iššūkius.